'\" t
.\"     Title: bugle
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: July 2010
.\"    Manual: Bugle user manual
.\"    Source: BUGLE 0.0.20150628
.\"  Language: English
.\"
.TH "BUGLE" "3" "July 2010" "BUGLE 0.0.20150628" "Bugle user manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bugle \- An OpenGL debugging library
.SH "SYNOPSIS"
.HP \w'\fB\fBBUGLE_CHAIN\fR\fR\fB=\fR\fB\fIchain\fR\fR\fB\ \fR\fB\fBLD_PRELOAD\fR\fR\fB=\fR\fBlibbugle\&.so\fR\fB\ \fR\fB\fIprogram\fR\fR\ 'u
\fB\fBBUGLE_CHAIN\fR\fR\fB=\fR\fB\fIchain\fR\fR\fB \fR\fB\fBLD_PRELOAD\fR\fR\fB=\fR\fBlibbugle\&.so\fR\fB \fR\fB\fIprogram\fR\fR [\fIargument\fR...]
.SH "DESCRIPTION"
.PP
Bugle
is a library that intercepts calls to OpenGL functions, in much the same way that many memory debuggers do\&. Calls are run through a number of user\-specified
filter\-sets, including one that invokes the original call\&.
.PP
In addition,
\fBgldb-gui\fR(1)
allows an OpenGL application to be debugged by detecting OpenGL errors and showing OpenGL state\&. For common usage this may be the most convenient way to use
bugle\&.
.PP
The
\fBBUGLE_CHAIN\fR
environment variable specifies a
filter\-set chain, which is simply a collection of filter\-sets with options\&. Chains are defined in the configuration file,
$HOME/\&.bugle/filters
(see
the section called \(lqCONFIGURATION\(rq)\&.
.SH "CONFIGURATION"
.PP
You can create filter\-set chains in the file
$HOME/\&.bugle/filters\&. It is possible to use
bugle
without creating this file, but it will simply pass all calls straight through to the real OpenGL library\&. This is not particularly useful unless you are using
\fBgldb-gui\fR(1)\&. A sample file is available in
doc/examples/filters
in the source distribution\&.
.PP
The file is text\-based\&. Comments begin with a
#
and continue to the end of the line\&. Strings should be quoted with double\-quotes, and backslash acts as an escape character in the usual way (including escaping of newlines)\&. Other white\-space is ignored\&. Each chain is specified as
.sp
.if n \{\
.RS 4
.\}
.nf
chain \fIchain\fR
{
    \fIfilter\-set\fR
    \fIfilter\-set\fR
    \fIfilter\-set\fR
    \&.\&.\&.
}
.fi
.if n \{\
.RE
.\}
.sp
Filter\-sets are specified as
.sp
.if n \{\
.RS 4
.\}
.nf
filterset \fIfilterset\fR [\fIkey\fR [inactive]]
{
    \fIoption\fR \(lq\fIvalue\fR\(rq
    \fIoption\fR \(lq\fIvalue\fR\(rq
    \fIoption\fR \(lq\fIvalue\fR\(rq
    \&.\&.\&.
}
.fi
.if n \{\
.RE
.\}
.PP
The
\fIkey\fR
may be used to toggle the filter\-set at run\-time (not all filter\-sets support this yet, and those that do will not always work)\&. Key names are based on X KeySyms (see
<X11/keysymdefs\&.h>
for a list)\&. They may also be prefixed with
C\-,
A\-
or
S\-
to indicate that the key must be combined with
Ctrl,
Alt
or
Shift
respectively\&. Some filter\-sets have options which are keys; these take the same format\&. The Windows build current only supports alphabetic keys (together with the
Ctrl,
Alt
and
Shift
modifiers)\&.
.PP
If you don\*(Aqt need to specify any options, it is also legal to omit the braces\&. Boolean options may be specified as
yes/no, as
true/false
or as
1/0\&.
.SH "FILTER-SETS"
.PP
Each filter\-set is documented in its own manual page e\&.g\&., the
\fBtrace\fR
filter\-set is documented in
\fBbugle-trace\fR(7)\&. You can get a brief list of available filter\-sets and their options by specifying an undefined chain e\&.g\&.,
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBBUGLE_CHAIN\fR=help \fBLD_PRELOAD\fR=libbugle\&.so \fBglxgears\fR
.fi
.if n \{\
.RE
.\}
.sp
.SH "ENVIRONMENT"
.PP
\fBBUGLE_CHAIN\fR
.RS 4
Specifies the filter\-set chain to use\&. If absent, the first chain in the configuration file is used\&.
.RE
.PP
\fBBUGLE_FILTERS\fR
.RS 4
If set, specifies an alternative configuration file to use instead of
$HOME/\&.bugle/filters\&.
.RE
.PP
\fBBUGLE_FILTER_DIR\fR
.RS 4
If set, specifies an alternative directory in which to find modules\&. This option is currently used by the test suite, and is not intended for general use\&.
.RE
.PP
\fBLD_PRELOAD\fR
.RS 4
Tells the linker to load
bugle
on Linux and similar systems\&. On Windows, you need to put the
bugle
version of
opengl32\&.dll
on the
\fBPATH\fR
ahead of the real version; the easiest way to do this is to copy it into the same directory as the executable you are debugging\&.
.RE
.PP
\fBBUGLE_DEBUGGER\fR, \fBBUGLE_DEBUGGER_HOST\fR, \fBBUGLE_DEBUGGER_PORT\fR
.RS 4
Configuration for remote TCP/IP debugging\&. Refer to
\fBgldb-gui\fR(1)
for details\&.
.RE
.SH "FILES"
.PP
$HOME/\&.bugle/filters
.RS 4
Lists the possible filter\-set chains\&. See
the section called \(lqCONFIGURATION\(rq
for a description of the format\&.
.RE
.PP
$HOME/\&.bugle/statistics
.RS 4
Definitions of statistics; see
\fBbugle-statistics\fR(5)
for more information\&.
.RE
.SH "BUGS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
OpenGL color\-index mode is not well supported\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Multi\-threaded applications that call the GL from more than one thread will break in various ways\&. The debugger filter\-set is particularly fragile\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Display lists may cause things to go wrong, depending on how they are created and what calls go into them\&.
.RE
.PP
For an up to date list of bugs, see the
\m[blue]\fBbug tracker\fR\m[]\&\s-2\u[1]\d\s+2
online\&. Also see the pages for individual filter\-sets for specific bugs affecting each\&.
.SH "AUTHOR"
.PP
bugle
is written and maintained by
Bruce Merry\&.
.SH "NOTES"
.IP " 1." 4
bug tracker
.RS 4
\%http://sourceforge.net/apps/trac/bugle/
.RE
